THESE ARE NOTES ONLY.  These changes are 
being considered and as yet are not part
of the current distribution of GrepBrowser.
-gmv 9/15/93.


Notes 7/22/93, Thursday

=======================================
Design notes for GrepBrowser
command line processing algorithm
for use with Windows' Program Manager.
=======================================

It should be possible to invoke GrepBrowser
with no args, 1 arg, or 2 args:

    GrepBrowser [grepFile] [searchFile]

This is the most simple syntax.  Its deficiencies
can be overcome through interaction with menu
commands.  A more sophisticated syntax with
flags and arguments or keywords and arguments
(e.g. grepFile: class.grp searchFile: app.h)
may be useful as features and options are added.
If more than two options can be specified from
the command line, the specification should be
indepent of the order in which the arguments 
appear.  This makes flags or keywords necessary
since the meaning of an argument can not be 
inferred from its position.  The issue of
complex command lines should be deferred until
menu commands have been implemented to handle
all possible ways the GrepBrowser might be
invoked.  The most obious case is making the
GrepBrowser useful when it is invoked with
no arguments.  To make this possible, extra
work must be done with the Menu command 
interface for GrepBrowser.


Unfortunately the goal of flexible interactive
operation of GrepBrowser leads to a redesign
of the menus and of user commands.
For example, what happens if the user invokes 
GrepBrowser with no arguments.  As it now works,
the application is essentially dead.  You have two
empty windows with no way of indicating a new
grepFile from which the browser should reinitialize
itself.

There is some potential confusion when redesigning
the menus.  Is opening a file to refer to setting
a new grepFile and reinitializing the grepList from
the file?  Or is opening a file to refer to opening
a text file for writing notes or editing source code?
It seems that in keeping with expectations with the
behavior of popular Windows and Mac software, that
File / Open should refer to a file.  The same applies
to New, Save, and Save As, also found in the File 
menu.  The thing to do (this is also a good demonstration
of polymorphism) is to put a 'New' or 'New List' command
as the first entry in the List.  Currently the first
entry is 'Open file.'  Again there is polymorphism
here.  (The File menu also has an Open command).
This points to a conceptual conflict.  Text editors
can be opened from either the File menu or the
List menu.  However, Save, in the File menu, applies
to the file selected in the list pane and implicitly
associated with the text (file contents) displayed
in the text pane.  Sometimes the File commands 
refer to independent text files 
(New Workspace, Open and sometimes they
refer to the selected GrepObject (file) in the
list pane (Save, Restore).  The File / Save As command
is never enabled--another potential confusion.

The style of the menus may seem normal to a Smalltalk
user, but it is likely to confuse people more 
familiar with other Windows applications.  Smalltalk
people take for granted that the commands in the
File menu operate on the active text pane--
most of the time.  Occassionally commands in the
File menu apply to activities with a wider scope
than the current window--the development environment
in Smalltalk (Open a Workspace, ClassHierarchyBrowser, 
or DiskBrowser).

    File
        New Workpace
        Open File
        Save
        Restore
        ----------
        About
    Edit (same)
    List
        New List
        Open File
        ----------
        Scroll Line
        Search File 
        ----------
        Info
        Reinitialize

Note in the above design, About is moved from
the List menu to the File menu and Save As is
removed from the File menu.  New List and
Search File commands are added to the List
menu.

Error checking and recovery needs to be added.
Grep lists should allow comments.  If a line
begins with #, it is a comment.  Blank lines
should be ignored.  There should be an option
to strip the file:lineNumber: string from the
text of the GrepObject.  It should be possible
to embed relevant browser options at the 
beginning of the data file.

If a line is encountered in which a lineNumber
is specified without a file AND no searchFile 
has been specified, a warning dialog should give 
the user a chance to specify a search file.
This question should only be asked on the
first encounter of a lineNumber with no file
during the parse of the grepList.  The answer
to the warning will determine how any other
lines with missing files will be handled.  If
the user indicates 'No' wish to specify a search
files, all lines missing file names will
be treated like comments and ignored.  If the
user says 'Yes' and indicates a searchFile,
all lines missing file names subsequently 
encounted will create GrepObjects for the 
specified searchFile.

GrepObjects should be given knowledge of their
original specification so that modified grepLists
can be reconstructed and written back to disk.
In addition to fields already in GrepObjects,
GrepObjects should retain:

    printString             string which appears in GrepBrowser list pane
    specificationString     line from which GrepObject was built
    lineNumber
    specHasFilename         boolean
    originalLineNumber      line number in specification

Strictly speaking, the last two fields are not required.
This information can always be obtained from the original
specification string.  At least methods returning this
information should be supplied, even if it is necesary
to parse the original string again.  It's best to think
of the later two fields as a cache to enable quick 
scan and update for a potentially large list of GrepObjets.
One field is a boolean and the other is an Integer so even
for a list of 1000 items the extra memory required should
be under 5K.  Measurements should be taken for updating
large lists with and without the cache; preserving the
data in fields may not even make a noticeable difference.